<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.8.5"/>
<title>NDK Programmer&#39;s Guide: CPU Features</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="navtree.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="resize.js"></script>
<script type="text/javascript" src="navtree.js"></script>
<script type="text/javascript">
  $(document).ready(initResizable);
  $(window).load(resizeHeight);
</script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
 <tbody>
 <tr style="height: 56px;">
  <td style="padding-left: 0.5em;">
   <div id="projectname">NDK Programmer&#39;s Guide
   </div>
  </td>
 </tr>
 </tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.5 -->
</div><!-- top -->
<div id="side-nav" class="ui-resizable side-nav-resizable">
  <div id="nav-tree">
    <div id="nav-tree-contents">
      <div id="nav-sync" class="sync"></div>
    </div>
  </div>
  <div id="splitbar" style="-moz-user-select:none;"
       class="ui-resizable-handle">
  </div>
</div>
<script type="text/javascript">
$(document).ready(function(){initNavTree('md_3__key__topics__c_p_u__support__c_p_u-_f_e_a_t_u_r_e_s.html','');});
</script>
<div id="doc-content">
<div class="header">
  <div class="headertitle">
<div class="title">CPU Features </div>  </div>
</div><!--header-->
<div class="contents">
<div class="textblock"><p>This NDK provides a small library named "`cpufeatures`" that can be used at runtime to detect the target device's CPU family and the optional features it supports.</p>
<h2>Usage</h2>
<p>The library is available as an import module. To use it, you must:</p>
<ul>
<li>List '<code>cpufeatures</code>' in your list of static library dependencies, as in: <pre class="fragment">LOCAL_STATIC_LIBRARIES := cpufeatures
</pre></li>
<li>At the end of your Android.mk, import the '<code>android/cpufeatures</code>' module, as in: <pre class="fragment">$(call import-module,android/cpufeatures)
</pre></li>
<li>In your source code, include the header named <code>&lt;cpu-features.h&gt;</code></li>
</ul>
<p>Here is a simple example: </p>
<pre class="fragment">    &lt;project-path&gt;/jni/Android.mk:
        LOCAL_PATH := $(call my-dir)

        include $(CLEAR_VARS)
        LOCAL_MODULE := &lt;your-module-name&gt;
        LOCAL_SRC_FILES := &lt;your-source-files&gt;
        LOCAL_STATIC_LIBRARIES := cpufeatures
        include $(BUILD_SHARED_LIBRARY)

        $(call import-module,android/cpufeatures)
</pre><h2>Features</h2>
<p>Two functions are provided for now: </p>
<pre class="fragment">    AndroidCpuFamily android_getCpuFamily();
</pre><p>Returns a value matching the CPU family/architecture supported by the current process as an enum. Currently, the following families are defined:</p>
<ul>
<li><code>ANDROID_CPU_FAMILY_ARM</code></li>
<li><code>ANDROID_CPU_FAMILY_X86</code></li>
<li><code>ANDROID_CPU_FAMILY_MIPS</code></li>
<li><code>ANDROID_CPU_FAMILY_ARM64</code></li>
<li><code>ANDROID_CPU_FAMILY_X86_64</code></li>
<li><code>ANDROID_CPU_FAMILY_MIPS64</code></li>
</ul>
<p>Note that when running a 32-bit executable on a 64-bit system, this function will return the 32-bit family value only.</p>
<p>Secondly:</p>
<pre class="fragment">    uint64_t android_getCpuFeatures();
</pre><p>Returns the set of optional features supported by the device's CPU. The result is a set of bit-flags, each corresponding to one CPU Family-specific optional feature.</p>
<p>Currently, only the following flags are defined, for the 32-bit ARM CPU Family:</p>
<ul>
<li><code>ANDROID_CPU_ARM_FEATURE_VFPv2</code><br/>
 Indicates that the device's CPU supports VFPv2 instruction set. Most ARMv6 CPUs support these.</li>
<li><code>ANDROID_CPU_ARM_FEATURE_ARMv7</code><br/>
 Indicates that the device's CPU supports the ARMv7-A instruction set as supported by the "armeabi-v7a" abi (see CPU-ARCH-ABIS.html). This corresponds to Thumb-2 and VFPv3-D16 instructions.</li>
<li><p class="startli"><code>ANDROID_CPU_ARM_FEATURE_VFPv3</code><br/>
 Indicates that the device's CPU supports the VFPv3 hardware FPU instruction set extension. Due to the definition of 'armeabi-v7a', this will always be the case if ANDROID_CPU_ARM_FEATURE_ARMv7 is returned.</p>
<p class="startli">Note that this corresponds to the minimum profile VFPv3-D16 that <em>only</em> provides 16 hardware double-precision FP registers.</p>
</li>
<li><code>ANDROID_CPU_ARM_FEATURE_VFP_D32</code><br/>
 Indicates that the device's CPU supports 32 hardware double-precision FP registers instead of 16. Note that there are still only 32 single- precision registers mapped to the same register banks.</li>
<li><code>ANDROID_CPU_ARM_FEATURE_NEON</code><br/>
 Indicates that the device's CPU supports the ARM Advanced SIMD (a.k.a. NEON) vector instruction set extension. Note that ARM mandates that such CPUs also implement VFPv3-D32, which provides 32 hardware FP registers (shared with the NEON unit).</li>
<li><code>ANDROID_CPU_ARM_FEATURE_VFP_FP16</code><br/>
 Indicates that the device's CPU supports instructions to perform floating-point operations on 16-bit registers. This is part of the VFPv4 specification.</li>
<li><code>ANDROID_CPU_ARM_FEATURE_VFP_FMA</code><br/>
 Indicates that the device's CPU supports fused multiply-accumulate VFP instructions extension. Also part of the VFPv4 specification.</li>
<li><code>ANDROID_CPU_ARM_FEATURE_NEON_FMA</code><br/>
 Indicates that the device's CPU supports fused multiply-accumulate NEON instructions extension. Also part of the VFPv4 specification.</li>
<li><code>ANDROID_CPU_ARM_FEATURE_IDIV_ARM</code><br/>
 Indicates that the device's CPU supports Integer division in ARM mode. Only available on recent CPUs (e.g. Cortex-A15).</li>
<li><code>ANDROID_CPU_ARM_FEATURE_IDIV_THUMB2</code><br/>
 Indicates that the device's CPU supports Integer division in Thumb-2 mode. Only available on recent CPUs (e.g. Cortex-A15).</li>
<li><code>ANDROID_CPU_ARM_FEATURE_iWMMXt</code><br/>
 Indicates that the device's CPU supports extension that adds MMX registers and instructions. This is only available on a few XScale- based CPU.</li>
<li><code>ANDROID_CPU_ARM_FEATURE_LDREX_STREX</code><br/>
 Indicates that the device's CPU supports LDREX and STREX instructions available since ARMv6. Together they provide atomic update on memory with the help of exclusive monitor.</li>
</ul>
<p>And the following flags for the 32-bit x86 CPU Family:</p>
<ul>
<li><code>ANDROID_CPU_X86_FEATURE_SSSE3</code><br/>
 Indicates that the device's CPU supports the SSSE3 instruction extension set. Note that this is unlike SSE3 which is required by the x86 NDK ABI.</li>
<li><code>ANDROID_CPU_X86_FEATURE_POPCNT</code><br/>
 Indicates that the device's CPU supports the POPCNT instruction.</li>
<li><code>ANDROID_CPU_X86_FEATURE_MOVBE</code><br/>
 Indicates that the device's CPU supports the MOVBE instruction. This one is specific to some Intel IA-32 CPUs, like the Atom.</li>
</ul>
<p>And the following flags for the 64-bit ARM CPU Family:</p>
<ul>
<li><code>ANDROID_CPU_ARM64_FEATURE_FP</code><br/>
 Indicates that the device's CPU has Floating Point (FP) unit. All Android ARM64 devices are required to support this feature.</li>
<li><code>ANDROID_CPU_ARM64_FEATURE_ASIMD</code><br/>
 Indicates that the device's CPU has Advanced SIMD (ASIMD) unit. All Android ARM64 devices are required to support this feature.</li>
<li><code>ANDROID_CPU_ARM64_FEATURE_AES</code><br/>
 Indicates that the device's CPU supports AES instructions.</li>
<li><code>ANDROID_CPU_ARM64_FEATURE_CRC32</code><br/>
 Indicates that the device's CPU supports CRC32 instructions.</li>
<li><code>ANDROID_CPU_ARM64_FEATURE_SHA1</code><br/>
 Indicates that the device's CPU supports SHA1 instructions.</li>
<li><code>ANDROID_CPU_ARM64_FEATURE_SHA2</code><br/>
 Indicates that the device's CPU supports SHA2 instructions.</li>
<li><code>ANDROID_CPU_ARM64_FEATURE_PMULL</code><br/>
 Indicates that the device's CPU supports 64-bit PMULL and PMULL2 instructions.</li>
</ul>
<p>Other CPU families do not have extensions listed at the moment, which means that android_getCpuFeatures() will return 0 for them.</p>
<p>The following function is also defined to return the max number of CPU cores on the target device: </p>
<pre class="fragment">    int  android_getCpuCount(void);
</pre><h2>Important Note</h2>
<p>The cpufeatures library will be updated to support more CPU families and optional features in the future. It is designed to work as-is on all official Android platform versions.</p>
<h2>Change History</h2>
<p>Please see the comments in <code>$NDK/sources/android/cpufeatures/cpu-features.c</code> for the complete change history for this library. </p>
</div></div><!-- contents -->
</div><!-- doc-content -->
<!-- start footer part -->
<div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
  <ul>
    <li class="footer">Generated on Wed Jun 25 2014 00:51:19 for NDK Programmer&#39;s Guide by
    <a href="http://www.doxygen.org/index.html">
    <img class="footer" src="doxygen.png" alt="doxygen"/></a> 1.8.5 </li>
  </ul>
</div>
</body>
</html>
